MemBrowse Memory Report

Top 10 targets by memory change (%) (out of 2471 targets) View Project Dashboard →

Hardware-in-the-loop (HIL) Test Report

hfp.json

✅ 39 passed · ❌ 17 failed · ⚪ 0 skipped · blank not run

tinyusb-esp.json

✅ 10 passed · ❌ 14 failed · ⚪ 0 skipped · blank not run

Thank you for your work, beside auto reviews, there is a need of some architectural changes:

API shaping

tuh_audio_descriptor_cb and tuh_audio_mount_cb_t should be removed as these are class specific details, we can't expect every user to read UAC specification.
Instead we should provide a list of supported format and sample frequency , similar to aplay --dump-hw-params or Windows audio device properties tab, then the class driver select the corresponding alt settings and sample frequency based user input.
It also makes later UAC2 support easier.
Anyway tuh_descriptor_get_configuration exist if someone needs the detail.

Buffering and packet scheduling

Similar to device driver, FIFO should be included in host driver.
Packet scheduling should be implemented for OUT terminal, when non-integer sample rate is selected eg. 44.1k, the driver should send 9* 44 slots packets and 1* 45 slots packet.
(Optional) feedback support - feedback can be implemented in the same time as packet scheduling, using device feedback sample rate as reference.

I've first completed the API design modifications. Please see if it works

As I commented earlier, the class driver should provide a WASAPI/ALSA-like high-level API for audio streaming, while keeping the USB Audio topology private.

We can keep the limitation that there is only one logical stream in each direction per instance (AC interface), which is the most common case.

If an instance has multiple Audio Streaming interfaces or alternate settings in one direction, their supported configurations can be combined into the corresponding logical stream. The driver keeps the mapping from each configuration to its interface, alternate setting, and endpoint.

This follows the general WASAPI exclusive-mode and ALSA hw: model: applications select channel count, sample format, and sample rate, while the driver performs the hardware-specific mapping.

Proposed API

Only discrete configurations need to be supported initially. Continuous sample-rate ranges can be rejected or ignored explicitly.

typedef enum {
  TUH_AUDIO_FORMAT_S8,
  TUH_AUDIO_FORMAT_S16_LE,
  TUH_AUDIO_FORMAT_S24_3LE,
  TUH_AUDIO_FORMAT_S24_LE,
  TUH_AUDIO_FORMAT_S32_LE
} tuh_audio_format_t;

typedef struct {
  tuh_audio_format_t format;
  uint32_t sample_rate;
  uint8_t channels;
} tuh_audio_stream_config_t;

typedef void (*tuh_audio_configure_cb_t)(
  uint8_t idx,
  tusb_dir_t direction,
  tusb_xfer_result_t result,
  uintptr_t user_data);

Each entry is a complete supported tuple, avoiding invalid combinations between independent format, rate, and channel lists.

bool tuh_audio_stream_exists(uint8_t idx, tusb_dir_t direction);

uint8_t tuh_audio_config_count(uint8_t idx, tusb_dir_t direction);

bool tuh_audio_config_get(
  uint8_t idx,
  tusb_dir_t direction,
  uint8_t config_idx,
  tuh_audio_stream_config_t* config);

bool tuh_audio_configure(
  uint8_t idx,
  tusb_dir_t direction,
  tuh_audio_stream_config_t const* config,
  tuh_audio_configure_cb_t complete_cb,
  uintptr_t user_data);

tuh_audio_configure() should require an exact supported tuple and asynchronously:

1. Find its AS interface and alternate setting.
2. Issue SET_INTERFACE.
3. Open or reconfigure the selected endpoint.
4. Set the endpoint sampling frequency when supported.
5. Initialize the FIFO and packet scheduler.
6. Invoke complete_cb after the stream is ready or an operation fails.

Streaming should be frame-based:

uint32_t tuh_audio_write(uint8_t idx, void const* buffer, uint32_t frame_count);
uint32_t tuh_audio_read(uint8_t idx, void* buffer, uint32_t frame_count);

uint32_t tuh_audio_write_available(uint8_t idx);
uint32_t tuh_audio_read_available(uint8_t idx);

bool tuh_audio_start(uint8_t idx, tusb_dir_t direction);
bool tuh_audio_stop(uint8_t idx, tusb_dir_t direction);

The class driver should own endpoint selection, FIFO management, transfer replenishment, fractional packet scheduling, and optional feedback processing.

Basic microphone example

The application selects a supported 48 kHz, mono, 16-bit capture configuration without accessing USB interfaces, alternate settings, or endpoint addresses.

static uint8_t mic_idx = TUSB_INDEX_INVALID_8;
static bool mic_ready;
static int16_t mic_samples[48];

static void mic_configured(uint8_t idx, tusb_dir_t direction,
                           tusb_xfer_result_t result, uintptr_t user_data) {
  (void) user_data;

  if (direction == TUSB_DIR_IN && result == XFER_RESULT_SUCCESS) {
    mic_ready = tuh_audio_start(idx, TUSB_DIR_IN);
  }
}

void tuh_audio_mount_cb(uint8_t idx) {
  if (!tuh_audio_stream_exists(idx, TUSB_DIR_IN)) {
    return;
  }

  for (uint8_t i = 0; i < tuh_audio_config_count(idx, TUSB_DIR_IN); i++) {
    tuh_audio_stream_config_t config;
    if (tuh_audio_config_get(idx, TUSB_DIR_IN, i, &config) &&
        config.format == TUH_AUDIO_FORMAT_S16_LE &&
        config.sample_rate == 48000 &&
        config.channels == 1) {
      mic_idx = idx;
      (void) tuh_audio_configure(idx, TUSB_DIR_IN, &config, mic_configured, 0);
      return;
    }
  }
}

void tuh_audio_umount_cb(uint8_t idx) {
  if (idx == mic_idx) {
    mic_idx = TUSB_INDEX_INVALID_8;
    mic_ready = false;
  }
}

void audio_app_task(void) {
  const uint32_t frame_count = TU_ARRAY_SIZE(mic_samples);
  if (mic_ready && tuh_audio_read_available(mic_idx) >= frame_count) {
    (void) tuh_audio_read(mic_idx, mic_samples, frame_count);
    // Process 1 ms of 48 kHz mono audio here.
  }
}

Correctness issues

1. Audio Host can consume MIDI interfaces.
   audioh_open() continues across every TUSB_CLASS_AUDIO interface. MIDI Streaming uses the same class with another subclass, and Audio Host is registered first. Parse only associated Audio Streaming interfaces, preferably using the AC header’s interface collection.

2. Alternate settings are overwritten and opened prematurely.
   Every discrete format must remain a separate internal configuration. Do not open every endpoint during descriptor parsing; open or reconfigure only the alternate setting selected by tuh_audio_configure().

3. SET_INTERFACE failures are ignored.
   Check the return value of tuh_interface_set() and xfer->result. A submission failure currently stalls enumeration, while a failed transfer can still mount the device.

4. Transfer parameters are insufficiently validated.
   Validate instance state, direction, buffers, frame counts, and endpoint packet limits before submitting transfers.

5. Feature Unit request lengths are hard-coded.
   UAC1 mute uses a one-byte value while volume uses two bytes. The current generic API always transfers two bytes.

6. Failed isochronous transfers reach application callbacks.
   audioh_xfer_cb() should not report failed, stalled, or aborted transfers as valid audio data.

7. The example can overflow its TX buffer.
   Mono-to-stereo conversion doubles the received byte count without bounding it against the TX buffer and selected OUT packet size.

8. Control-transfer byte order is incomplete.
   Setup-packet multibyte fields require little-endian conversion. Three-byte sampling frequencies and Feature Unit values must be explicitly converted to host-order values.

This smaller API should be enough for a first UAC1 host implementation while leaving room for multiple streams, continuous rates, conversion, and channel mapping later.